home *** CD-ROM | disk | FTP | other *** search
/ QuickTime 2.0 Developer Kit / QuickTime 2.0 Developer Kit.iso / mac / MAC / Programming Stuff / Interfaces / CIncludes / Translation.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-11-11  |  11.9 KB  |  306 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Translation.h
  3.  
  4.      Copyright:    © 1984-1994 by Apple Computer, Inc.
  5.                  All rights reserved.
  6.  
  7.      Version:    Universal Interfaces 2.0a3  ETO #16, MPW prerelease.  Friday, November 11, 1994. 
  8.  
  9.      Bugs?:        If you find a problem with this file, send the file and version
  10.                  information (from above) and the problem description to:
  11.  
  12.                      Internet:    apple.bugs@applelink.apple.com
  13.                      AppleLink:    APPLE.BUGS
  14.  
  15. */
  16.  
  17. #ifndef __TRANSLATION__
  18. #define __TRANSLATION__
  19.  
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. /*    #include <ConditionalMacros.h>                                */
  25.  
  26. #ifndef __FILES__
  27. #include <Files.h>
  28. #endif
  29. /*    #include <MixedMode.h>                                        */
  30. /*    #include <OSUtils.h>                                        */
  31. /*        #include <Memory.h>                                        */
  32.  
  33. #ifndef __COMPONENTS__
  34. #include <Components.h>
  35. #endif
  36.  
  37. #ifndef __TRANSLATIONEXTENSIONS__
  38. #include <TranslationExtensions.h>
  39. #endif
  40. /*    #include <Quickdraw.h>                                        */
  41. /*        #include <QuickdrawText.h>                                */
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47. #if GENERATINGPOWERPC
  48. #pragma options align=mac68k
  49. #endif
  50.  
  51. #ifdef __CFM68K__
  52. #pragma lib_export on
  53. #endif
  54.  
  55. typedef short DocOpenMethod;
  56.  
  57.  
  58. enum {
  59.     domCannot,
  60.     domNative,
  61.     domTranslateFirst,
  62.     domWildcard
  63. };
  64.  
  65. /* 0L terminated array of OSTypes, or FileTypes*/
  66. typedef OSType TypesBlock[64];
  67.  
  68. typedef OSType *TypesBlockPtr;
  69.  
  70. /* Progress dialog resource ID*/
  71.  
  72. enum {
  73.     kTranslationScrapProgressDialogID = -16555
  74. };
  75.  
  76. /* block of data that describes how to translate*/
  77. struct FileTranslationSpec {
  78.     OSType                            componentSignature;
  79.     const void                        *translationSystemInfo;
  80.     FileTypeSpec                    src;
  81.     FileTypeSpec                    dst;
  82. };
  83. typedef struct FileTranslationSpec FileTranslationSpec;
  84.  
  85. typedef FileTranslationSpec *FileTranslationSpecArrayPtr;
  86.  
  87. /*****************************************************************************************
  88. * 
  89. *   GetFileTypesThatAppCanNativelyOpen
  90. * 
  91. *  This routine returns a list of all FileTypes that an application can open by itself
  92. * 
  93. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  94. *             appSignature        signature (creator) of application
  95. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  96. * 
  97. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  98. */
  99. extern pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  100.  TWOWORDINLINE(0x701C, 0xABFC);
  101. /*****************************************************************************************
  102. * 
  103. *  ExtendFileTypeList
  104. * 
  105. *  This routine makes a new list of file types that can be translated into a type in the given list
  106. *  Used by StandardFile
  107. * 
  108. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  109. *             numberOriginalTypes        number of file types in orgTypeList
  110. *              extendedTypeList        pointer to a buffer to be filled with file types
  111. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  112. * 
  113. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  114. *             numberExtendedTypes        number of file types put in extendedTypeList
  115. */
  116. extern pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  117.  TWOWORDINLINE(0x7009, 0xABFC);
  118. /*****************************************************************************************
  119. * 
  120. * 
  121. *  This routine checks if a file can be opened by a particular application.
  122. *  If so, it returns if it needs to be translated first, and if so then how.
  123. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  124. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  125. * 
  126. *  Enter:    targetDocument        document to check if it can be opened
  127. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  128. *             appSignature        signature (creator) of application to open doc
  129. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  130. *             onlyNative            whether to consider if document can be translated before opening
  131. *             howToOpen            pointer to buffer in which to put how the document can be opened
  132. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  133. * 
  134. *  Exit:    howToOpen            whether file needs to be translated to be read
  135. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  136. *             returns                noErr, noPrefAppErr
  137. */
  138. extern pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  139.  TWOWORDINLINE(0x701E, 0xABFC);
  140. /*****************************************************************************************
  141. * 
  142. *  GetFileTranslationPaths
  143. * 
  144. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  145. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  146. * 
  147. *  Enter:    srcDoc            source file or NULL for all matches
  148. *             dstDoc            destination FileType or NULL for all matches
  149. *             maxResultCount
  150. *             resultBuffer
  151. *  Exit:    number of paths
  152. */
  153. extern pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  154.  TWOWORDINLINE(0x7038, 0xABFC);
  155. /*****************************************************************************************
  156. * 
  157. *  GetPathFromTranslationDialog
  158. * 
  159. *  This routine, with a given document, application, and a passed typelist will display the
  160. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  161. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  162. *  The routine returns the translation path information.
  163. * 
  164. *  Enter:    theDocument            FSSpec to document to open
  165. *             theApplication        FSSpec to application to open document
  166. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  167. *                                 you would like the documented translated to.  Order most perferred
  168. *                                 to least.
  169. * 
  170. *  Exit:    howToOpen            Translation method needed to open document
  171. *             howToTranslate        Translation specification
  172. *             returns                Any errors that might occur.
  173. */
  174. extern pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  175.  TWOWORDINLINE(0x7037, 0xABFC);
  176. /*****************************************************************************************
  177. * 
  178. *   TranslateFile
  179. * 
  180. *  This routine reads a file of one format and writes it to another file in another format. 
  181. *  The information on how to translated is generated by the routine CanDocBeOpened.
  182. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  183. *  The destination file must not exist.  It is created by this routine.  
  184. * 
  185. *  Enter:    sourceDocument            input file to translate
  186. *             destinationDocument        output file of translation
  187. *             howToTranslate            pointer to info on how to translate
  188. *  Exit:    returns                    noErr, badTranslationSpecErr 
  189. */
  190. extern pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  191.  TWOWORDINLINE(0x700C, 0xABFC);
  192. /*****************************************************************************************
  193. * 
  194. *   GetDocumentKindString
  195. * 
  196. *  This routine returns the string the Finder should show for the "kind" of a document
  197. *  in the GetInfo window and in the kind column of a list view.  
  198. * 
  199. *  Enter:    docVRefNum        The volume containing the document
  200. *             docType            The catInfo.fdType of the document
  201. *             docCreator        The catInfo.fdCreator of the document
  202. *             kindString        pointer to where to return the string
  203. * 
  204. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  205. *             returns            noErr, or afpItemNoFound if kind could not be determined
  206. */
  207. extern pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  208.  TWOWORDINLINE(0x7016, 0xABFC);
  209. /*****************************************************************************************
  210. * 
  211. *  GetTranslationExtensionName
  212. * 
  213. *  This routine returns the translation system name from a specified TranslationSpec
  214. * 
  215. *  Enter:    translationMethod    The translation path to get the translation name from
  216. * 
  217. *  Exit:    extensionName        The name of the translation system
  218. *             returns                Any errors that might occur
  219. */
  220. extern pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  221.  TWOWORDINLINE(0x7036, 0xABFC);
  222. /*****************************************************************************************
  223. * 
  224. *  GetScrapDataProcPtr
  225. * 
  226. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  227. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  228. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  229. *  with a list all the formats that you have available to be translated, and the length of each.
  230. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  231. *  the formats that 'fmts' list said was available.
  232. * 
  233. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  234. *             dataH                    Handle in which to put the requested data
  235. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  236. *             
  237. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  238. */
  239. typedef pascal OSErr (*GetScrapDataProcPtr)(ScrapType requestedFormat, Handle dataH, void *srcDataGetterRefCon);
  240.  
  241. #if GENERATINGCFM
  242. typedef UniversalProcPtr GetScrapDataUPP;
  243. #else
  244. typedef GetScrapDataProcPtr GetScrapDataUPP;
  245. #endif
  246.  
  247. enum {
  248.     uppGetScrapDataProcInfo = kPascalStackBased
  249.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  250.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ScrapType)))
  251.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Handle)))
  252.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(void*)))
  253. };
  254.  
  255. #if GENERATINGCFM
  256. #define NewGetScrapDataProc(userRoutine)        \
  257.         (GetScrapDataUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetScrapDataProcInfo, GetCurrentArchitecture())
  258. #else
  259. #define NewGetScrapDataProc(userRoutine)        \
  260.         ((GetScrapDataUPP) (userRoutine))
  261. #endif
  262.  
  263. #if GENERATINGCFM
  264. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)        \
  265.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppGetScrapDataProcInfo, (requestedFormat), (dataH), (srcDataGetterRefCon))
  266. #else
  267. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)        \
  268.         (*(userRoutine))((requestedFormat), (dataH), (srcDataGetterRefCon))
  269. #endif
  270.  
  271. typedef GetScrapDataUPP GetScrapData;
  272.  
  273. /*****************************************************************************************
  274. * 
  275. *  TranslateScrap
  276. * 
  277. *  This routine resizes the destination handle and fills it with data of the requested format.
  278. *  The data is generated by translated one or more source formats of data supplied by
  279. *  the procedure srcDataGetter.  
  280. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  281. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  282. * 
  283. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  284. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  285. *             destinationFormat            Format of data desired
  286. *             destinationData                Handle in which to store translated data
  287. *             
  288. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  289. */
  290. extern pascal OSErr TranslateScrap(GetScrapData sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  291.  TWOWORDINLINE(0x700E, 0xABFC);
  292.  
  293. #ifdef __CFM68K__
  294. #pragma lib_export off
  295. #endif
  296.  
  297. #if GENERATINGPOWERPC
  298. #pragma options align=reset
  299. #endif
  300.  
  301. #ifdef __cplusplus
  302. }
  303. #endif
  304.  
  305. #endif /* __TRANSLATION__ */
  306.